Using JSON Forms

This guide introduces how to navigate JSON Forms in Itential Automation Platform (IAP) and how to use the Forms application to generate a JSON Schema representation of a form. There are two main components to the JSON Forms application that enable management of forms, a forms collection view and a form builder. Forms can be used throughout IAP. At a high level, this is achieved by the JSON Forms builder providing the functionality to generate a JSON Schema representation of a form via drag-and-drop user interface.

Accessing JSON Forms

To access JSON Forms go to IAP → Automation Studio → JSON Forms.

JSON Forms is listed in the left navbar as its own subcategory in Automation Studio.

Figure 1: JSON Forms

Collection View

To open the Collection view of JSON Forms, click the Find an Automation link on the main welcome page of Automation Studio.

Figure 2: Find an Automation

The Collection page displays (card-based layout) and JSON FORMS is located in the top tab bar. To access a specific JSON Form, workflow, or other automation, select the corresponding tab at the top to see the card view (collection) of all the available workflows, automations, etc.

Figure 3: Collection View

The following actions can be taken from the Collection page.

Action	Icon	Description
Refresh		Refreshes the page.
Import		Imports a workflow.
Select All		Selects all the workflows on the active tab and page.
Delete		Permanently removes a selected workflow.
Export		Exports a selected workflow.
Sort		Sort by name, date created, last modified, or by tags.
Search		Search for a workflow by name or other criteria.

Create a New JSON Form

To create a new JSON Form:

1. Navigate to the main Automation Studio application page.
2. Click the + Create an Automation link to open the Create dialog.
3. Select JSON Form from the dropdown list.
4. Enter a JSON Form name (required) and brief description (optional).
5. Click Create to save. The JSON Form is added to the Collection page.

Figure 4: Create JSON Form

Delete a JSON Form

You can delete an existing JSON Form using the card menu or by selecting a specific JSON Form.

Figure 5: JSON Form Card Controls

Using the Card Menu

To delete a JSON Form using the card menu:

1. Click the stacked dots icon inside the JSON Form card to display the menu options.
2. Click Delete to delete the JSON Form.

Figure 6: Delete JSON Form

Using the Select Button

To select a JSON Form (or multiple JSON Forms) for deletion:

1. Click the select button to mark the JSON Form as selected.

2. Click the trashcan icon to delete all selected forms.

   

3. Click the unselect icon to unselect all selected forms.

   

Export Forms to JSON Files

You can also export a JSON file representation of a form using Forms. To access the Forms application:

1. Go to the main welcome page of Automation Studio.

2. Go to the left navbar and click the dropdown arrow to open the Forms menu.

   Figure 7: Forms

   

3. Click any form in the list to navigate to the Form Builder for that particular form.

   Figure 8: Forms List

   

4. Click the stacked dots icon in the top toolbar of the Form to display more options. From the menu that opens, you can view metadata, clone a form, revert changes made to a form, export a form to a JSON file, or delete a form.

   Figure 9: Form Toolbar and Menu Options

   

   Note: For more details on the Forms application, see the Forms user guide.

5. Click the Export form option to open the export modal.

   Figure 10: Export Form

   

6. Select Save File to download a JSON file representation of the form. Be sure to remember the location where the JSON file is saved.

   Figure 11: Save Export File

   

7. You can also export a form into a JSON file from the Collection view.

8. Click the select button to select multiple Forms for bulk export.

9. Click the stacked dots icon in the toolbar to display the Export menu options.

10. Click the Export icon to export all selected forms to JSON files.

    Figure 12: Export from Collection View

    

Import JSON Files

To import a form from a JSON file:

1. Click the Import icon from the top toolbar on the Automation Studio homepage.

   Figure 13: Import from Automation Studio Toolbar

   

2. Alternately, you can go to the Collection view of JSON Forms and select the Import icon.

   Figure 14: Import JSON Forms

   

3. One or more JSON files (forms) can be imported at a time.

Clone a JSON Form

To clone (copy) a JSON Form:

1. Click the stacked dots icon inside of the card.

2. Click the Clone menu option to create a copy of the JSON Form.

   Figure 15: Clone Menu Option

   

3. The Clone Form dialog displays. Save the Form with a different name.

4. Click Clone to save the JSON Form.

   Figure 16: Clone JSON Form

   

Preview a JSON Form

To preview a JSON Form:

1. Click the stacked dots icon inside of the card.

2. Click the Preview menu option to show a preview of the JSON Form.

   Figure 17: Preview Menu Option

   

3. The Preview Form dialog displays. You can maximize and minimize the dialog by clicking the exapnder in the upper-right.

   Figure 18: Preview Form

   

4. Click Show Form to display the JSON schema. Click Close to return to the preview modal.

   Figure 19: JSON Form Schema

   

Sort JSON Forms

To sort JSON Forms by name, date created, last modified, or by tags:

1. Click the sort icon to modify the sort order (ascending or descending).

2. Use the dropdown to change the property the sort is performed on.

   Figure 20: Sort JSON Forms

   

View and Update JSON Form Details

Click the eye icon in the top toolbar to open JSON form details. This drawer displays information about who created the form and when, along with who last updated the form and when. From the form details screen, the form name and description can be changed.

Figure 21: View JSON Form Metadata

Working with the JSON Form Builder

In Form Builder it is possible to change the structure and element composition of previously created forms. From the Form Builder view you can update a form name, add new form elements, change existing form elements, restructure a form through drag and drop reordering, and inspect different types of form previews.

Figure 22: JSON Form Builder

The sections below provide an overview of how to build and edit a JSON Form using Form Elements. The element bin is on the right side of the form. There you can find all available elements that can be added to a JSON Form.

Figure 23: Layout & Form Elements

Layout Elements

The Layout elements are not used to directly provide an input field, but rather to group elements or provide unique data structures. There are three types:

• Tables store form elements to build repeatable groupings of related form elements. Each element added to a table becomes a column in the table. Once the form is rendered, tables allow rows to be added that are made up of these sub-elements for capturing data.
• Schema Combinations allow a user to combine schemas and group them into options using the schema combinations element.
• Containers store form elements to build logical groupings of related form elements. These sub-elements are rendered vertically.

Form Elements

Form Elements are used to provide fields that capture values on input. There are five types:

• Text Input — Used to capture short string values.
• Text Area — Used to capture long string values.
• Number Input — Used to capture integer or decimal values.
• Checkbox — Used to capture boolean values.
• Dropdown — Used to capture strings from a set of options.
• File Upload - Used to define an input element for file uploads.

Adding Elements to a JSON Form

The Form Builder canvas is where the JSON form is built by dragging elements onto the "Drop elements here" zone. As the form is being built, it can be previewed and the generated form schemas can be inspected. For example, to add a dropdown option to a JSON form, drag-and-drop the element labeled Dropdown.

Figure 24: Form Builder Canvas

Changing Element Properties

A form element can be edited by hover over the stacked dots and then clicking the grid icon next to the element name.

Figure 25: Change Element Properties

A Configure dialog will open the available properties for editing a form element. Click Save to retain your changes.

Figure 26: Configure Element Properties

Referenced below is a list of available properties currently supported for each form element. To update the name of a layout element, edit the Label field.

Element	Properties
Text Field	Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Text Area	Label, Placeholder, Description, Required, Pattern Validation, Dynamic Validation
Number Field	Label, Placeholder, Description, Required, Dynamic Validation
Checkbox	Label, Description, Checked
Dropdown	Label, Placeholder, Description, Required, Static Options, Dynamic Options, Pattern Validation, Dynamic Validation

Property	Description
Label	The name of the field.
Placeholder	A user prompt or hint usually displayed inside of the input field before data is entered.
Description	A short description of the field. This displays below the field label.
Static Options	A list of static values to be used as options for dropdowns.
Dynamic Options	Used to retrieve a list of dynamic values through an HTTP request by providing a specific configuration to setup data binding via a request and a value mapping.
Checked	When set to yes, this defaults the value of a checkbox to true.
Required	A value input is required.
Pattern Validation	A regular expression used to validate an input value.
Dynamic Validation	Used to validate an input value through an HTTP request by providing a specific configuration to setup a data binding via a request and a value mapping.

Adding Dropdown Options

There are two methods of adding dropdown options, static and dynamic.

Static Options

To add static options for a dropdown, set the options type to static. Click the + Option button to add items to the draggable list and use the input field to change the value of the dropdown option. Use the drag handle icon to reorganize the list items via drag and drop. Use the trashcan icon to remove an item from the dropdown options.

Figure 27: Static Options Editor

Dynamic Options

To utilize dynamic options for a dropdown, the following fields have to be configured.

Property	Description
Method	The request method.
Request Body	The request body in the form of JSON.
Base URL	The request scheme/protocol + authority + optional port.
API Route	The request path + optional query.
Source Property	A property on the response that contains the array to use as the dropdown options.
Property Key	A property that exists for each of the objects within the array selected on the source property that will become the value of the dropdown options.

The fields that are set in the form configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

1. Select a Method. If POST is selected, then the Request Body field requires input.
2. Input the Base URL.
3. Input the API Route.
4. Click the Make API Call button to view the response from the request.
5. Select the Source Property.
6. Select the Property Key.
7. Click the Query Data button to see a preview of the values that will populate as the dropdown's options.
8. Click the Back button once all configurations have been set.

Figure 28: Dynamic Options Editor

Adding Validation

There are two methods of adding validation, pattern and dynamic. These can be used together or independently. Both can be added by clicking the + Validation button on the form elements editor, where this option is enabled.

Figure 29: Validation Editor

Static Validation

To add a pattern validation input a regular expression into the text field labeled Pattern.

Dynamic Validation

To utilize dynamic validation, the following fields have to be configured.

Property	Description
Method	The request method.
Request Body	The request body in the form of JSON.
Base URL	The request scheme/protocol + authority + optional port.
API Route	The request path + optional query.
Source Property	A property on the response that contains boolean value telling if the field value is valid. Currently, only truthy properties are support, meaning isValid will work, but isInvalid will not.
Dynamic Request Body Property	A property on the request body.
Error Message	The error message for when the input value is not valid.

The fields configure the HTTP request and the data mapping that will occur when the form is rendered. Follow these steps to configure the request:

1. Select POST Method and input the Request Body. The Request Body is a mock body for when the request is actually made on during form field input.
2. Input the Base URL.
3. Input the API Route.
4. Click the Make API Call button to see the response from the request.
5. Select the Source Property.
6. Click the Query Data button to see a preview of the boolean value that determines a valid input value.
7. Select the Dynamic Request Body Property to pick which request body property will have its value replaced by the input value being validated.
8. Input the Error Message that is displayed when the input value is invalid.
9. Click the Back button once all configurations have been set.

Adding Schema Combinations

JSON schemas can be combined using a few keywords in JSON Schema. This can be done using keywords like allOf, oneOf, and anyOf. Using the JSON forms canvas, a user can combine schemas and group them into options using the schema combinations element. Using keywords oneOf and anyOf, a user can fill out only one option in the form, whereas using the option allOf allows a user to fill out all the options in the form.

To add a schema combination to the form canvas, drag and drop the Schema Combinations Element from the form elements on the right onto the canvas. Users can add options to this combination by clicking on the Add Option button; different form elements can be dragged and dropped into these options. A schema combination in the form canvas looks as below:

Figure 30: Schema Combination Canvas

To select what type of combination that particular combination should be like, users can click the Format dropdown and one of the three keywords can be selected.

Figure 31: Schema Combination Dropdown

While filling out the form in the renderer, the element renders a dropdown which allows a user to select which dropdown to fill out. Depending on the option selected in the dropdown the sub-schema corresponding to that option is rendered.

Figure 32: Form Preview Option 1

Reorder Elements

Any form element can be reordered using the drag handle icon to move it from its original location to a new location and dropping it.

Delete Elements

Click the trash can to delete an element from the form.

Save Form Changes

Click the Save button to capture any changes made to a form.

Preview a Form

As a form is being built, the form can be previewed by clicking the eye icon of the Form Builder canvas.

Figure 33: Form Preview

Inspect the Generated Schemas

To evaluate the underlying data structures that are generated as a form is built, click the Show Form Data button in the footer of the Preview Form dialog. This displays the JSON Schema, UI Schema, Binding Schema, Validation Schema and other schema inputs for the form. Click Show Form to return to preview mode.

Figure 34: Schema Preview

Render JSON Schema Task

With JSON Forms it is possible to create forms rather quickly in a workflow using just a JSON schema. You can use the renderJSONSchema task available in JSON Forms via Automation Studio. It is a manual task that requires schema as input, creates a form using the schema, renders it and then forgets the form.

Using the Task

To use the renderJSONSchema task:

1. Navigate to Automation Studio and create a new automation.
2. Under the list of tasks available in the right pane, select JsonForms.
3. Add RenderJsonSchema to the canvas. This task alone is enough to render a form.
4. Double-click on the task and the task editor (shown below) will display.

Figure 35: RenderJsonSchema Task Preview

Task Inputs

As seen in the image above, the task accepts five inputs. Each of these inputs define how the form elements are structured, rendered and behave.

Input Parameter	Description
jsonSchema	As the name suggests this input expects the user to enter a JSON schema. The jsonSchema entered as input to this variable will define the structure of the entire form.
uiSchema	If you have worked with the JSON Forms app you might have seen the UI schema in the preview for a form built using canvas. The uiSchema defines the widgets to be used for the form elements.
bindingSchema	The bindingSchema input is used to define the external data binding with a form element, usually a dropdown field populated with options. It allows a user to define the hyper schema for an API. It is also used to define dynamic validation. To learn more about binding schema, refer to this Itential guide.
validationSchema	The validationSchema input is used to define dynamic validations for a field in the form.
formData	This input uses instance data to populate the form with. The instance data is a JSON object with a key-value format, where key is the field name and value is the value it takes when the form is rendered. The values inside a form rendered with instance data can be edited.

Examples

Using the sample schemas detailed below as input, render a form using the renderJSONSchema task. Once task inputs are complete, save the automation and start the job.

jsonSchema

{
    "title": "inputFields",
    "description": "",
    "type": "object",
    "required": [],
    "properties": {
        "text1": {
            "type": "string",
            "title": "Text 1",
            "description": ""
        },
        "textArea1": {
            "type": "string",
            "title": "Text Area 1",
            "description": ""
        },
        "number1": {
            "type": "number",
            "title": "Number 1",
            "description": ""
        },
        "checkbox1": {
            "type": "boolean",
            "title": "Checkbox 1",
            "description": "",
            "default": false,
            "enum": [
                true,
                false
            ]
        },
        "dropdown1": {
            "type": "string",
            "title": "Dropdown 1",
            "description": "",
            "enum": ["item 1", "item 2"]
        }
    }
}

uiSchema

{
    "text1": {
        "ui:placeholder": "Enter text only"
    },
    "textArea1": {
        "ui:placeholder": "Enter text",
        "ui:widget": "textarea"
    },
    "number1": {
        "ui:placeholder": "Enter a number",
        "ui:widget": "updown"
    },
    "dropdown1": {
        "ui:placeholder": "Select an item"
    }
}

Render JSON Schema Form

Once the job is executed, you can work on the task from Job Manager, where you can also view task details and the incoming variables.

Using the Form

When you click the work task, the rendered form will display as shown below. The inputFields in the form will reflect the fields defined in the JSON schema sent as input variables.

Figure 36: Rendered Form

Complete the inputFields in the form and then click the Confirm button to complete the task.

Figure 37: Input Fields

Once the task is complete, the Outgoing tab in Task History will show that the form data is exported.

Figure 38: Outgoing Form Data

Note: This task will not create a form instance in the json-form application. When you open the json-forms app, you will not see this form.